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About This Manual 


This manual describes the administration of the Location Broker, a 
component of the Digital Remote Procedure Call (DECrpc) Version 1.0, 
which is based on and is compatible with Apollo’s Network Computing 
System (NCS). Location Broker software provides name service runtime 
support for distributed application programs that use remote procedure calls. 
These programs can include both user applications and system facilities. 

This manual is a new manual in the DECrpc documentation set. The manual 
is based on the manual Managing NCS Software from the Apollo Systems 
Division of Hewlett Packard. 


Audience 

This manual is for system administrators who are setting up the Location 
Broker and who are administrating systems that are running distributed 
applications. It explains how to establish and maintain runtime support for 
distributed applications. 


Organization 

This manual contains four chapters, a glossary, and an index. 

Chapter 1 describes the basic concepts of the Location Broker. 

Chapter 2 describes lb_admin, the Location Broker administrative tool, 
and its use. 

Chapter 3 describes how to set up and run the Location Broker processes on 
homogeneous networks and networks that include Apollo systems. It also 
describes how to maintain the Location Brokers. 

Chapter 4 contains the reference pages for the lb_admin administrative 
tool and the Location Broker processes llbd and nrglbd. 

If you want to set up the Location Broker immediately, you can follow the 
procedures in Chapter 3 without reading any of the other chapters. 





Related Documentation 

For more information on topics related to DECrpc, see the following 
documents: 

DECrpc Programming Guide 

This book is a reference manual for programmers developing 
distributed applications. It provides programming information and 
examples of programs using remote procedure calls, including calls to 
the Location Broker. The manual also includes reference pages for 
DECrpc library routines and utilities. 


Conventions 

The following conventions are used in this guide: 


special 


variable 

literal 

t ] 


UPPERCASE 


example 

example 
new term 

$ 

# 


In text, each mention of a specific command, option, 
partition, pathname, directory, or file is presented in this 
type. 

In syntax descriptions, this type indicates terms that are 
variable. 

In syntax descriptions, this type indicates terms that are 
constant and must be typed just as they are presented. 

In syntax descriptions, brackets indicate terms that are 
optional. 

In syntax descriptions, a horizontal ellipsis indicates that 
the preceding item can be repeated one or more times. 

The Location Broker software differentiates between 
lowercase and uppercase characters. Enter uppercase 
characters only where specifically indicated by an 
example or a syntax line. 

In examples, computer output text is printed in this type. 
In examples, user input is printed in this bold type. 

In text, new terms are introduced in this bold type. 

This is the default user prompt in multiuser mode. 

This is the default privileged user prompt. 

A vertical ellipsis indicates that a portion of an example 
that would normally be present is not shown. 
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Location Broker Concepts 


The Location Broker is a component of DECrpc, which is based on and is 
compatible with the Network Computing System (NCS), a set of tools for 
heterogeneous distributed computing. This chapter introduces the Location 
Broker and describes the role that it plays in distributed applications. 


1.1 Location Broker Overview 

The Location Broker is a name service that provides clients with information 
about the locations of objects and interfaces. An object is an entity accessed 
by well-defined operations. A file, a directory, a database, a serial line, a 
printer, and a processor can all be objects. Each interface is a set of 
operations that can be applied to any of those objects. 

Every object has a type. For example, you can classify printer queues as 
objects of the type printqueue, accessed through a printqueue_ops interface 
that includes operations to add, delete, and list jobs in the queues. 

DECrpc identifies every object, type, and interface by a Universal Unique 
Identifier (UUID). A UUID is defined as a 16-byte quantity identifying the 
host on which the UUID is created and the time at which it is created. Six 
bytes identify the time, two are reserved, and eight identify the host. 

The uuid_gen utility provided in DECrpc generates UUIDs as text strings 
or as data structures defined in C syntax. The string representation used by 
the NIDL Compiler, a tool for developing distributed applications, and by 
DECrpc utilities consists of 28 hexadecimal characters arranged as in this 
example: 

3a2f883c4000.0d.00.00.fb.40.00.00.00 

Servers register with the Location Broker their socket addresses and the 
objects and interfaces to which they provide access. Clients issue requests to 
the Location Broker for the locations of objects and interfaces they wish to 
access. The broker then returns database entries that match an object, type, 
interface, or some combination of these, as specified in the request. 

The Location Broker also implements the RPC message-forwarding 
mechanism. If a client sends a request for an interface to the Location 
Broker forwarding port on a host, the broker automatically forwards the 
request to the appropriate server on the host. 




1.2 Location Broker Software 

The Location Broker consists of the following interrelated components: 

• The Local Location Broker 

• The Global Location Broker 

• The Location Broker Client Agent 

The Local Location Broker (LLB) is an RPC server that maintains a 
database of information about objects and interfaces located on the local host. 
The LLB runs as the process llbd. The LLB provides access to its 
database for application programs and also provides the Location Broker 
forwarding service. An LLB must run on any host that runs RPC servers. 

The Global Location Broker (GLB) is an RPC server that maintains 
information about objects and interfaces throughout the network or internet. 
The GLB runs as the process nrglbd. 

The Location Broker Client Agent is a set of library routines that 
application programs call to access LLB and GLB databases. Any client that 
uses Location Broker routines is actually making calls to the Client Agent. 
The Client Agent interacts with the LLBs and the GLB to provide access to 
their databases. Figure 1-1 shows the relationships among application 
programs, the Location Broker components, and the Location Broker 
databases. 
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Figure 1-1: Location Broker Software 
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1.2.1 Location Broker Data 

Each entry in a Location Broker database contains information about an 
object, an interface, and the location of a server that exports the interface to 
the object. Table 1-1 lists the fields in a database entry. Use the lb_admin 
command, described in Chapter 2, to view database entries. 
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Table 1-1: Location Broker Database Entry 


Field 

Description 

Object UUID 

The unique identifier of the object 

Type UUID 

The unique identifier that specifies the type of the 
object 

Interface UUID 

The unique identifier of the interface to the object 

Flag 

A flag that indicates whether the object is global (and 
therefore should be registered in the GLB database) or 
local (and therefore should be registered in the LLB 
database) 


All global registrations are also registered with the LLB 
on the host where the server registers. 

Annotation 

Sixty-four characters of user-defined information 

Socket address length 

The length of the socket address field 

Socket address 

The location of the server that exports the interface to 
the object 


Because each database entry contains one object UUID, one interface UUID, 
one type UUID, and one socket address, a Location Broker database must 
have an entry for each possible combination of object, interface, type, and 
socket address. 

Thus, the database must have 10 entries for a server that: 

• Listens on two sockets, socket_a and socket_b 

• Exports interface_l for object_x, object_y, and 
object_z 

• Exports interface_2 for object_p and object_q 

• Has only one type for ob ject_p and ob ject_q 

You can look up Location Broker information by using any combination of 
the object UUID, type UUID, and interface UUID as keys. You can also 
request the information from the GLB database or from a particular LLB 
database. Therefore, you can obtain information about all objects of a 
specific type, all hosts with a specific interface to an object, or even all 
objects and interfaces at a specific host. For example, you could find the 
addresses of all remotely available array processors by looking up all entries 
with the arrayproc type. 
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1.2.2 Location Broker Registrations and Lookups 

The Location Broker Client Agent is a set of library routines that applications 
use to access and modify the LLB and GLB databases. When a program 
issues any Location Broker call, the call actually goes to the local host Client 
Agent. The Client Agent then does the work to add, delete, or look up 
information in the appropriate Location Broker database. 

Figure 1-2 illustrates a typical case in which a client requires a particular 
interface to a particular object but does not know the location of a server 
exporting the interface to the object. In this figure, an RPC server registers 
itself with the Location Broker by calling the Client Agent in its host (la). 
The Client Agent registers the server with the LLB at the server host (lb) 
and with the GLB (lc). To locate the server, the client issues a Location 
Broker lookup call (2a). The Client Agent on the client host sends the 
lookup request to the GLB, which returns it through the Client Agent to the 
client (2b). The client can then use RPC calls to communicate directly with 
the located server (3a, 3b). 


Figure 1-2: Client Agents and Location Brokers 
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A client might know the host where the object is located without knowing 
the port number used by the server. The client can specify this information 
in its lookup call. In this case, the Client Agent directly interrogates the LLB 
of the remote host, as illustrated in Figure 1-3. 
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Figure 1-3: Client Agent Doing a Lookup at a Known Host 
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1.3 The Local Location Broker 

The LLB runs as the llbd process. It has two major functions: 

• It maintains a database of the objects and interfaces that are exported by 
servers running on the host. 

• It acts as a forwarding agent for requests. 

Although it is recommended that you run an 1 lbd process on every host, 
the process is required only on hosts that mn RPC servers. 


1.3.1 The Local Database 

The LLB database provides location information about interfaces on the local 
host. This information is used by both local and remote applications. To 
look up information in an LLB database, an application queries the LLB 
through a client agent. (See Figure 1-1.) 
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1.3.2 The LLB Forwarding Agent 

The forwarding facility of the LLB eliminates the need for a client to know 
the specific port that a server uses and thereby helps to conserve well known 
ports. The forwarding agent listens on one well known port for each address 
family. It forwards any messages that it receives to the local server that 
exports the requested object. 

Forwarding is particularly useful when the requestor of a service already 
knows the host where the server is running. Such a server can use a 
dynamically assigned opaque port and register only with the LLB at its local 
host, not with the GLB. To access the server, a client needs only to specify 
the object, the interface, and the host, but not a specific port. 


1.4 The Global Location Broker 

The GLB manages information about the objects and interfaces that are 
available to users on the network. An RPC server registers itself with the 
Location Broker by calling the Client Agent on its host. The Client Agent 
adds the registration information to the LLB database at the server host and 
also sends the information to the GLB. 

When a client requires the services of a particular interface, it issues a 
Location Broker lookup call to the Client Agent on its host. The Client 
Agent sends the lookup request to the GLB. The GLB extracts the required 
information from its database and returns it, through the Client Agent, to the 
client. The client can then use RPC system calls to communicate directly 
with the located server. 

When the GLB receives calls, either from a server or from lb_admin, to 
register or unregister an object, the GLB process updates the GLB database. 
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Ib_admin: The Location Broker 
Administrative Tool 


2 


The Location Broker administrative tool, lb_admin, allows you to inspect 
or modify the contents of a Location Broker database. Use lb_admin to 
look up information, add new entries, and delete existing entries in any LLB 
or GLB database. 

The lb_admin tool is useful both for inspecting the contents of the 
Location Broker databases and for correcting database errors. For example, 
if a server starts while the nrglbd is not running, you can manually enter 
the information for the server in the GLB database. Similarly, if a server 
terminates abnormally without unregistering itself, you can use lb_admin 
to manually remove the server entry from the GLB database, the LLB 
database, or both. 


2.1 Starting lb_admin 

Because lb_admin is a foreign command, you must define it in the startup 
file SYS$STARTUP:RPC$UCX_STARTUP.COM as follows: 

$lb_admin :== $rpc$exe:lb_admin 

After defining the command, start lb_admin by typing the command at the 
prompt: 

$ lb_admin 

Table 2-1 lists the qualifiers to the lb_admin command. 

Note 

This tool is available on VMS systems, ULTRIX systems, and 
other versions of the UNIX operating system. The command 
interface is common across all these systems, and therefore is not 
in a traditional DCL style. 

For this command, precede qualifiers with a hyphen (-), rather 
than the customary slash (/). 

You must define each DECrpc command as a foreign command. 




Table 2-1: 

lb_admin Qualifiers 

Qualifier 

Function £ 

-nq 

Do not query for verification of wildcard expansions in 
unregister operations. This option has no effect on the 
clean command. However, if you use wildcards for object 
and type, and specify interface and IP address, lb_admin 
deletes all interfaces of the same type as that of the interface 
specified. 

-version 

Display the version of the Network Computing Kernel (NCK) 
that this lb admin belongs to, but do not start lb_admin. 

(NCK is part of the Network Computing System.) 


At the lb_admin: prompt, enter any of the lb_admin commands, 
described in Section 2.2, and in the lb_admin reference page. 

2.2 The lb_admin Command-Line Interface 

Table 2-2 describes the commands that you can enter at the lb_admin 
prompt. Table 2-3 describes the arguments and values for the commands. 
Section 2.4 contains examples of the commands. 

Table 2-2: lb admin Commands 


Command Syntax and Function 


add 

a [dd] object type interface location annotation [flag ] 

Synonym for register. 

clean 

c[lean] 

Find and delete obsolete entries in the current database 

The lb_admin utility tries to contact each registered server. 

If the server responds, lb admin leaves its registration entry 
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Table 2-2: (continued) 


Command 


delete 

help 

lookup 

quit 


Syntax and Function 

intact. If the server does not respond, lb_admin tries to look 
up its registration in the LLB database at the host where the 
server is located, tells you the result of this lookup, and asks 
whether you want to delete the entry. 

The lb_admin utility queries even if you used the nq 
qualifier. If a server responds but its UUIDs do not match the 
entry in the database, lb_admin tells you this result and asks 
whether you want to delete the entry. Section 2.4 includes an 
example of deleting an interface from the database. 

d [ e 1 et e ] object type interface location 
Synonym for unregister. 
h[elp] [ command] or ? [ command] 

Without a command name, lists the lb_admin commands. 
With a command name, displays a description of that command. 

1 [ookup] object type interface 

Look up all entries with matching object, type, and interface 
fields. You can use asterisks as wildcards in any of the 
arguments. If you enter all arguments as wildcards or enter no 
arguments, lookup displays the entire database. 

q[uit] 

Exit lb admin and return to DCL. 
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Table 2-2: (continued) 


Command 

Syntax and Function 

register 

add 

r[egister] object type interface location annotation [flag] 
a[dd] object type interface location annotation [flag] 

Register the specified entry. You must supply the object, type, 
interface, location, and annotation fields. Wildcards are 
allowed in the object, type, and inteiface fields. 

You can enter a string of up to 64 characters to annotate the 
entry. Double quotation marks delimit a string that contains a 
space, or a null annotation. Use a backslash to escape double 
quotation marks in the annotation string. 

Values for flag are local or global. A local entry 
indicates the entry should be marked for local registration only; 
this is the default. A global entry indicates the entry should 
be marked for registration in both the LLB and GLB databases. 
The field is stored with the entry and does not affect where the 
entry is registered. 

set_broker 

The register command registers an entry only in the 
specified database. If you set the broker to the LLB and then 
register an entry with the global flag, the entry is registered 
only in the LLB database, and you must use a separate 
command to register it in the GLB database. 

s[et broker] [broker switch] location 

Set the host for the current LLB or GLB. If you specify 
global as the broker_switch, set broker sets the 
current GLB. Otherwise, it sets the current LLB. Issue 
use_broker, not this command, to determine whether 
subsequent operations access the LLB or the GLB. 

set timeout 

set_t [ imeout ] [short / long] 

Set the timeout period used by lb_admin for all of its 
operations. With an argument of short or long, 
set_timeout sets the timeout accordingly. With no 
argument, it displays the current timeout value. 
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Table 2-2: (continued) 


Command 

Syntax and Function 

unregister 

delete 

u [nregister] object type interface location 
d [ e 1 et e ] object type interface location 

Unregister all entries that match the specified arguments. An 
asterisk in the object, type, or interface field matches any other 
entry with an asterisk in that field. 

Unless you suppress queries by specifying the nq qualifier to 
lb admin, unregister asks you whether to delete each 
matching entry. 

Respond y[es] to delete all entries. 

Respond n[o] to leave the entry in the database. 

Respond g[o] to delete all remaining database entries that 
match, with no query. 

Respond q[uit] to terminate the unregister operation, without 
deleting any more entries. 

If you use wildcards, lb_admin prompts you to verify that 
you wish to delete each entry. 

use_broker 

With the nq qualifier, if you use wildcards for object and type, 
and specify interface and IP address, lb_admin deletes all 
interfaces of the specified type. 

us[e_broker] brokerjswitch 

Specify whether to look up, register, or unregister entries in the 
current LLB database or in the current GLB database. Use 
set_broker to set the particular LLB or GLB to be accessed. 


Table 2-3 lists the values that you specify to lb_admin as arguments in the 
command interface. 
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Table 2-3: lb_admin Fields and Arguments 


Field 

Argument 

object 

type 

interface 

Object, type, and interface UUIDs have the following format (in 
which n is a hexadecimal digit): 

nnnnnnnnnnnn.nn.nn.nn.nn.nn.nn.nn.nn 

location 

An asterisk is the wildcard for this argument. 

A socket address specifier consisting of an address family, a 
host name, and a port. The syntax is family: name [port ]; 
for instance, ip: cactus [104]. 

DECrpc supports only the Internet address family, indicated as 

ip. 

The name argument is the host name, in a format suitable for 
the address family. The default is the local host. 

annotation 

The port argument is an integer port number. The enclosing 
brackets are required if you are specifying the port field. If 
omitted, the default is socket_$unspec_port. 

A string of up to 64 characters annotating the entry. In the 
command interface, you must use double quotation marks 
around any string that includes spaces, and you can embed a 
quotation mark in the string with a preceding backslash. 

flag 

In the command interface, specify as an argument either 
local or global. This flag marks a database entry to 
indicate whether that entry should be registered globally. 
However, it does not affect how the entry is registered when 
you use the register command. If omitted, the default is 
local. 

broker_switch 

In the command interface, specify local or global. This 
argument of a set broker or use broker command 
determines whether the LLB or the GLB is being specified. If 
omitted, the default is local. 


2.3 Examples of lb_admin Commands 

The examples in this section illustrate the lb_admin commands. 

Although the register command example shows the command split 
across two lines for printing purposes, you must enter the entire command on 
a single line. 
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Example 2-1 shows the display from the lb_admin help command. 
Typing a question mark (?) at the lb_admin prompt produces the same 
display. 


Example 2-1: The lb_admin Help Command 


lb_admin: help 
Known commands are: 
a [dd] 

r [egister] 
set_[timeout] 
e[xit] 


c[lean] 
u[nregister] 
us[e_broker] 
q[uit] 


d[elete] 
s[et_broker] 
1[ookup] 
h[elp] 


Example 2-2 requests the use of the current GLB with the use_broker 
command and then displays the entire database with the lookup command 
with no arguments. 


Example 2-2: Displaying the Contents of a Database 

lb_admin: use_broker global 
lb_admin: lookup 

Data from GLB replica: ip:cactus 


object = * 
type = * 

interface = 43fdl54al696.02.82,b4.05.aO.00.00.00 
"DCC on desert" @ ip:desert[1481] global 
"DCC on cactus" @ ip:cactus[2455] global 
"DCC on ramada" @ ip:ramada[3168] global 


object = 
type = 
interface = 
"dec server on 


★ 


* 

4460c9baef60.02.82.b4.05.a0.00.00.00 
cactus" @ ip:cactus[2936] global 


Examples 2-3 and 2-4 show lb_admin register commands that 
register an interface, testregister, in the local database. Both 
examples use the lookup command to display the database with the added 
interface. Example 2-3 shows the use of a wildcard for the interface and 
Example 2-4 uses a UUID for the interface. 

Typically registration occurs from within a program. During test or debug 
situations, however, it may be convenient to manually register an interface 
without having to write code to do so. 
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Example 2-3: Registering an Interface (Wildcard for Interface) 

lbadmin: register * * * ip:cactus testregister local 
lb_admin: lookup 

object = 333b91c50000.0d.00.00.87.84.00.00.00 
type = 333b91de0000.0d.00.00.87.84.00.00.00 
interface = 333b2e690000.Od.00.00.87.84.00.00.00 
"non-replicated GLB" @ ip:cactus[1045] 


object = * 
type = * 

interface = 4460c9baef60.02.82,b4.05.aO.00.00.00 
"dcc_server on cactus" @ ip:cactus[3197] global 


object = * 
type = * 
interface = * 

"testregister" @ ip:cactus[0] 


Note 

Example 2-4 shows the command line continued on a second 
line because of the short line length of the manual. You would, 
however, type the command on a single line. 


Example 2-4: Registering an Interface (UUID for Interface) 


lb_admin: register * * 4279729d556c.02.82.b4.05.a0.00.00.00 
ip:cactus testuuid local 
lb_admin: lookup 


object = * 
type = * 

interface = 4279729d556c.02.82.b4.05.aO.00.00.00 
"testuuid" @ ip:cactus[0] 


lb_admin: 

Example 2-5 shows lb_admin commands that list the current database, 
delete a specific interface, and then list the database again. 
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Example 2-5: Deleting (Unregistering) an Interface 

1b_admin: 1ookup 


object = 333b91c50000.0d.00.00.87.84.00.00.00 
type = 333b91de0000.0d.00.00.87.84.00.00.00 
interface = 333b2e690000.Od.00.00.87.84.00.00.00 
"non-replicated GLB" @ ip:cactus[1045] 


object = * 
type = * 

interface = 4460c9baef60.02.82.b4.05.aO.00.00.00 
"dcc_server on cactus" @ ip:cactus[3197] global 


object = * 
type = * 
interface = * 
"testregister" @ 


lb admin: delete 


object = * 
type = * 
interface = * 

"testregister" @ ip:cactus[0] 
delete ? yes 
lb_admin: lookup 


object = 333b91c50000.0d.00.00.87.84.00.00.00 
type = 333b91de0000.0d.00.00.87.84.00.00.00 
interface = 333b2e690000.Od.00.00.87.84.00.00.00 
"non-replicated GLB" @ ip:cactus[1045] 


object = * 
type = * 

interface = 4460c9baef60.02.82,b4.05.aO.00.00.00 
"dcc_server on cactus" @ ip:cactus[3197] global 


ip:cactus[0] 

* * * ip:cactus U 


d A wildcard in a command field matches a corresponding interface field 
that also has an asterisk entry. This command, therefore, only deletes 
the interface for testregister, which is defined by an asterisk 
wildcard in each of its three fields. 


Example 2-6 illustrates the lb_admin clean command that cleans the 
database of interfaces that do not respond. 
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Example 2-6: Deleting Unresponding Interfaces 


lb_admin: clean 
working . . . 


object = * 
type = * 

interface = 4279729d556c.02.82.b4.05.aO.00.00.00 
"testregister" @ ip:cactus[0] 

Server not responding, but registered 
in remote llbd database. 

[using short timeouts] Delete? y 
1 entries deleted of 1 entries processed 
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Administering the Location Brokers 


This chapter provides guidelines for administering the Local and Global 
Location Broker in homogeneous networks and in networks that include 
Apollo systems. 


3.1 Guidelines for Configuring the Location Brokers 

The following sections provide guidelines for configuring the Local and 
Global Location Broker processes. 

3.1.1 Configuring the Local Location Broker Process 

The following guidelines will help you to configure the Local Location 
Broker (LLB) process: 

• Run the LLB process, 1 lbd, on any host where a Global Location 
Broker (GLB) or other RPC-based server runs. 

• Start the llbd from a system start-up command file as described in 
Section 3.2. 

Note 

If your system contains more than one network interface, 
the DECrpc software uses only the primary interface, which 
is set when you install UCX. It is the first name listed 
when you run the UCX SHOW INTERFACE command. 

3.1.2 Configuring the Global Location Broker Process 

The following guidelines will help you to configure the Global Location 
Broker process. 

Run the GLB process, nrglbd, on a single host in any network where 
RPC-based servers run. 




Note 


If the host running the nrglbd is taken off line, any system 
that requires global location data will be unable to run distributed 
applications. 

Section 3.3 describes procedures for restarting and maintaining 
the GLB and the GLB databases. 

An nrglbd communicates with clients by means of Internet Protocols (IP). 
In an internet, one nrglbd can run on each network, but each nrglbd 
services only the hosts in its own network. 

3.1.3 Configuring a Global Broker in Networks with Apollo 
Systems 

On any network that contains Apollo nodes, it is preferable to run the 
replicatable GLB process, glbd, on an Apollo system, rather than nrglbd 
on a Digital system. The following guidelines will help you to configure the 
replicating GLB process on an Apollo system: 

• If an Apollo system in the network is running a replicatable Global 
Location Broker process (glbd), use glbd on the Apollo system as 
the GLB process for the network. A replicated database provides 
increased performance and reliability. 

Refer to Managing NCS Software supplied with the Apollo system for 
procedures for administering the glbd. 

• Because the nrglbd and glbd processes do not interoperate, run 
only one or the other in a network. 

• If an Apollo node is acting as a gateway between two networks, a 
glbd running on that node can serve clients on both networks. For 
increased performance and reliability, replicate the GLB on one or more 
other Apollo systems on either network. 

• A glbd can communicate with another glbd only by means of 
Apollo Domain network communications protocols (DDS). Therefore, 
in an internet containing several GLB replicas, any gateways used by 
the GLB must support DDS. 


3.2 Procedures for Starting Location Broker Processes 

Start the Location Brokers in the following order: 

1. The LLB process, llbd 

2. The GLB process, nrglbd 
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3. Any other RPC-based servers 

The following sections describe the procedures for starting up the Local and 
Global Location Broker processes. 

3.2.1 Starting the Local Broker Process 

The command file SYS$STARTUP:RPC$UCX_STARTUP.COM starts the 
llbd process on a VMS system. The process should run as a detached 
process, independently of login activity, for as long as the system is up. 

The following example shows the line in the command procedure that starts 
the process: 

$ RUN/DETACHED/PRIV=SYSPRV/PROCESS_NAME=RPC$LLBD RPC$EXE:RPC$LLBD.EXE 

3.2.2 Starting the Global Location Broker Process 

The following command procedure starts the GLB process nrglbd on a 
VMS system: 

SYS$STARTUP:RPC$UCX_STARTUP.COM 

The process has no qualifiers and takes no arguments. It should run as a 
detached process, independently of login activity for as long as the system is 
up. 

The following example shows the line in the command procedure that starts 
the process. 

$ RUN/DETACHED/PRIV=SYSPRV/PROCESSNAME=RPC$NRGLBD RPC$EXE:RPC$NRGLBD.EXE 


3.3 Maintaining the Location Brokers 

When an llbd process is started on a system running the VMS operating 
system, it looks for the file RPC$EXE:RPC$LLBDBASE.DAT. If it is 
found, the llbd automatically registers all the servers listed in the file. 

When an nrglbd process is started on a system running the VMS operating 
system, it looks for the file RPC$EXE:RPC$GLBDBASE.DAT. If it is 
found, the nrglbd automatically globally registers all the servers listed in 
the file. 

The following sections provide information on changing the host running the 
GLB process and maintaining the Location Broker databases in case of 
system crash or downtime. The purpose of most of the procedures in the 
following sections is to provide up-to-date copies of the database files in case 
a host crashes or is taken off line. 
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3.3.1 Changing the GLB Host 

To change the host running the GLB process, you need to perform these 
steps: 

1. Copy the GLB database file, RPC$EXE:RPC$GLBDBASE.DAT on 
VMS systems, from the current GLB host to the new host. 

2. Stop the running GLB process on the old host. 

3. Start nrglbd on the new host by executing the startup procedure 
S YS$ST ARTUP: RPC$UCX_ST ARTUP.COM. 

4. Shut down the old GLB host. 

When you start nrglbd on the new machine before shutting down the old 
GLB machine, you allow application servers that may be running on the old 
GLB host to unregister from the nrglbd database file on the new GLB 
host. 

If this is not possible (due to a system crash or some other reason), run the 
lb_admin clean command on the new nrglbd host while the old 
nrglbd host is off line. The lb_admin clean command causes 
lb_admin to try to contact all registered servers. If a server is not 
responsive, lb_admin gives you the option of letting lb_admin send an 
unregistration request to the new nrglbd host. 


3.3.2 Recovering from a Crash of the GLB Host 

If the Global Location Broker host crashes and you restart nrglbd on the 
same system, all things should run as before as long as servers on other 
systems have not changed state. If, however, an application tries to contact a 
server that is no longer running or which has different port numbers, the 
application will fail. The application also will not see any new server 
registrations. 

If a copy of RPC$EXE:RPC$GLBDBASE.DAT is unavailable, you must 
create an up-to-date version of the file before restarting glbd. To do this, 
use lb_admin to query the llbd for registration data on every system 
running an RPC server and use lb_admin to register all servers with the 
GLB on the new host. Then, restart nrglbd, as described in Section 3.2. 

To make sure you have an up to date copy of 
RPC$EXE:RPC$GLBDBASE.DAT, write a command procedure that 
periodically copies the database file from the current nrglbd host to any 
other hosts that may want to run the nrglbd in the future. Because 
registrations and unregistrations of global data are normally done 
infrequently, this would ensure availability of a current copy. 
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To automatically start up nrglbd at a new host in case of a system crash, 
run a program that periodically makes a global lookup request. On failure, 
the program could spawn off a new process to start nrglbd on another host 
on the local network. 


3.3.3 Restarting a System Running Only the LLB 

If you start all RPC servers from a command procedure such as 
SYS$STARTUP:RPC$UCX_STARTUP.COM, and 
RPC$EXE:RPC$LLBDBASE.DAT is cleared on system startup, then no 
problems should be seen. When the llbd restarts, it will build a new 
RPC$EXE:RPC$LLBDBASE.DAT file. 

However, if some RPC server is initiated by a user, and 
RPC$EXE:RPC$LLBDBASE.DAT is not totally cleared on restart or the 
llbd process itself is terminated (with STOP pid) or for some reason dies, 
you can see problems when 1 lbd initializes from the old files. Old locally 
registered server information may exist that is no longer valid. In this case, 
however, only applications written to perform local lookups will be affected. 

Any user may correct local llbd registrations with either the lb_admin 
delete or clean commands. Once the old registrations are removed, you 
can manually enter new entries, or bring up RPC-based servers, or both. 

The nrglbd is included in the context of server. When an nrglbd is 
brought up, it registers its interfaces with the llbd. If you change the 
running nrglbd from one host to another (by stopping the nrglbd 
process on one host and restarting it on another), the host that was originally 
running the nrglbd retains its registration of the nrglbd interface. 

When a new RPC-based server registers on the host no longer running the 
nrglbd, the registration is forwarded to the new host running the nrglbd. 



3.3.4 Terminating RPC Servers 

Do not terminate registered RPC-based application servers (with STOP pid), 
unless it is absolutely essential, because the servers’ registration information 
will not be removed from the local or global database files. As a result, 
application client processes may try to bind to servers that are no longer 
available. 

Instead, all RPC servers should be written to have an exit handler to process 
the termination and initiate logic to unregister themselves from the LLB or 
GLB brokers. 

As part of the site-specific shutdown procedures, each server should have a 
dedicated shutdown procedure that forces an exit on the server to be 
terminated. Applications call the site-specific shutdown procedure before 
calling UCX$INET_SHUTDOWN. 
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This chapter contains reference pages for lb_admin, llbd, and 
nrglbd. 
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Ib_$admin 


Name 

lb_$admin - Location Broker Administrative Tool 

Format 

lb_$admin [ -version ] [ -nq] 

Note 

This tool is available on VMS systems, ULTRIX systems, and other 
versions of the UNIX operating system. The command interface is 
common across all these systems, and therefore is not in a traditional 
DCL style. 

For this command, precede qualifiers with a hyphen (-), rather than the 
customary slash (/). 

You must define each DECrpc command as a foreign command. 


Description 

The lb_$admin tool monitors and administers the registrations of DECrpc-based 
servers in Global Local Broker (GLB) or Local Location Broker (LLB) databases. A 
server registers Universal Unique Identifiers (UUIDs) specifying an object, a type, 
and an interface, along with a socket address specifying its location. A client can 
locate servers by issuing lookup requests to GLBs and LLBs. 

In accepting input or displaying output, lb_$admin uses either character strings or 
descriptive textual names to identify objects, types, and interfaces. A character string 
directly represents the data in a UUID in the following format, where each n is a 
hexadecimal digit: 

nnnnnnnnnnnn.nn.nn.nn.nn.nn.nn.nn.nn 

With lb_$admin, you examine or modify only one database at a time, referred to 
as the current database. The use_broker command selects the type of Location 
Broker database, GLB or LLB. The set_broker command selects the host whose 
LLB database is to be accessed. 

Information about the lb_$admin commands is available through the help 
command. 

Before invoking the lb_admin utility, define it as a foreign command in 
SYS$MANAGER:SYSLOGIN.COM, as shown in this example: 

$ lb_admin :== rpc$exe:rpc$lb_admin.exe 
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Qualifiers 

-nq Do not query for verification of wildcard expansions in 

unregister operations. 

-version Display the version of the Network Computing Kernel 

(NCK) that this lb_$admin belongs to, but do not start the 
tool. (NCK is part of the Network Computing System 
(NCS) on which DECrpc is based.) 

Commands 

In the descriptions of lookup, register, and unregister, th z object, type, 
and interface arguments can be either character strings representing UUIDs or textual 
names corresponding to UUIDs, as described earlier. 

In the descriptions of register and unregister, the location argument is a 
string in the format family :host[povt], where family is an address family, host is a 
host name, and port is a port number. The only value for family is ip. You can use 
a leading number sign (#) to indicate that a host name is in the standard numeric 
form. For example, ip:vienna[1756], and ip:#192.5.5.5[1791] are both acceptable 
location specifiers. 

a[dd] Synonym for register. 

c [lean] Find and delete obsolete entries in the current database. 

When you issue the clean command, lb_$admin attempts to 
contact each server registered in the database. If the server does not 
respond, lb_$admin tries to look up its registration in the LLB 
database at the host where the server is located, tells you the result of 
this lookup, and asks whether you want to delete the entry. If a 
server responds, but its UUIDs do not match the entry in the 
database, lb_$admin tells you this result and asks whether you 
want to delete the entry, even if you used the -nq qualifier to 
lb_$admin. 

There are two situations in which it is likely that a database entry 
should be deleted: 

• The server does not respond, lb_$admin succeeds in 

contacting the LLB at the host where the server is located, and 
the server is not registered with that LLB. The server is 
probably no longer running. 
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• A server responds, but its UUIDs do not match the entry in the 
database. The server that responded is not the one that 
registered the entry. 

Entries that meet either of these conditions are probably safe to delete 
and are considered eligible for automatic deletion (described in the 
next paragraph). In other situations, it is best not to delete the entry 
unless you can verify directly that the server is not running (for 
example, by listing the processes running on its host). 

When the clean command asks whether you want to delete an 
entry, choose one of the following responses: 

y[es] Delete the entry. 

n[o] Leave the entry intact in the current database. 

g[o] Invoke automatic deletion, in which all eligible entries (see 
the previous paragraph) are deleted and all ineligible entries 
are left intact, without your being queried, until all entries 
have been checked. 

q[uit] Terminate the clean operation. 


d[elete] Synonym for unregister. 
h[elp] [ command] or ? [command] 



Display a description of the specified command or, if none is 
specified, list all of the lb_$admin commands. 


l[ookup] object type interface 


Look up and display all entries with matching object , type , and 
interface fields in the current database. You can use asterisks as 
wildcards for any of the arguments. If all the arguments are 
wildcards, or if no arguments are given, lookup displays the entire 
database. 


q [uit ] Exit the lb_$admin session. 


r[egister] object type interface location annotation [flag] 


Add the specified entry to the current database. You can use an 
asterisk to represent the nil UUID in the object , type , and interface 
fields. 

The annotation is a string of up to 64 characters annotating the entry. 
Use double quotation marks (" ") to delimit a string that contains a 
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space or contains no characters. To embed a double quotation mark 
in the string, precede it with a backslash (\). 

The flag is either local (the default) or global, indicating 
whether to mark the entry for local registration only or for 
registration in both the LLB and the GLB databases. The flag is a 
field that is stored with the entry; it does not affect where the entry is 
registered. The set_broker and use_broker commands select 
the particular LLB or GLB database for registration. 

set_broke r [ broker_switch] location 

Set the host for the current LLB or GLB. If you specify global as 
the broker_switch, set_broker sets the current GLB; otherwise, it 
sets the current LLB. The host is a location specifier as described 
earlier, but the [port] portion is ignored and can be omitted. 

Issue the use_broker command, not the set_broker command, 
to determine whether subsequent operations will access the LLB or 
the GLB. 

set_t [imeout ] [short / long] 

Set the timeout period used by lb_$admin for all of its operations. 
With an argument of short or long, set_timeout sets the 
timeout accordingly. With no argument, it displays the current 
timeout value. 

u[nregister] object type interface location 

Delete the specified entry from the current database. 

You can use an asterisk as a wildcard in the object , type , and 
interface fields to match any value for the field. Unless you suppress 
queries by specifying the -nq qualifier of lb_$admin, 
unregister asks you whether to delete each matching entry. 
Choose one of the following responses: 

y[es] Delete the entry. 

n[o] Leave the entry in the database. 

g[o] Delete all remaining database entries that match, without 
your being queried. 

q[uit] Terminate the unregister operation, without deleting any 
more entries. 
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us [e_broker] [broker_switch] 

Select the type of database that subsequent operations will access, 
GLB or LLB. The broker switch is either global or local. If 
you do not supply a broker_switch, use_broker tells whether the 
current database is global or local. 

Use set_broker to select the host whose GLB or LLB is to be 
accessed. 


See Also 

llbd, nrglbd 
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Name 

llbd - Local Location Broker Process 

Format 

llbd [ -version ] 

Note 

This tool is available on VMS systems, ULTRIX systems, and other 
versions of the UNIX operating system. The command interface is 
common across all these systems, and therefore is not in a traditional 
DCL style. 

For this command, precede qualifiers with a hyphen (-), rather than the 
customary slash (/). 

You must define each DECrpc command as a foreign command. 


Description 

The Local Location Broker Process ( llbd ) is part of the Network Computing 
System (NCS). It manages the Local Location Broker (LLB) database, which stores 
information about RPC-based server programs running on the local host. 

A host must run llbd if it is to support the Location Broker forwarding function or 
to allow remote access (for example, by the lb_$admin tool) to the LLB database. 
In general, any host that runs an RPC-based server program must run an llbd, and 
llbd must be running before any such servers are started. Additionally, any 
network supporting RPC activity should have at least one host running a Global 
Location Broker Process ( nrglbd ). 

The command file SYS$STARTUP:RPC$UCX_STARTUP.COM starts the llbd 
process on a VMS system. The process should run as a detached process, 
independently of login activity, for as long as the system is up. 

The following example shows the line in the command procedure that starts the 
process: 

$ RUN/DETACHED/PRIV=SYSPRV/PROCESS NAME=RPC$LLBD RPC$EXE:RPC$LLBD.EXE 
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Qualifier 

-version Display the version of the Network Computing Kernel (NCK) that this 
llbd belongs to, but do not start the process. (NCK is part of the 
Network Computing System (NCS) on which DECrpc is based.) 

See Also 

lb_$admin, nrglbd 


4-8 Reference Pages 



nrglbd 


Name 

nrglbd - Non-Replicating Global Location Broker Process 

Format 

nrglbd [ -version ] 

Note 

This tool is available on VMS systems, ULTRIX systems, and other 
versions of the UNIX operating system. The command interface is 
common across all these systems, and therefore is not in a traditional 
DCL style. 

For this command, precede qualifiers with a hyphen (-), rather than the 
customary slash (/). 

You must define each DECrpc command as a foreign command. 


Description 

The Global Location Broker (GLB), enables clients to locate servers on a network or 
internet. The GLB database stores the locations (that is, the network addresses and 
port numbers) where server processes are running. The GLB maintains this database 
and provides access to it. 

The nrglbd daemon should run as a detached process. It requires no qualifiers or 
arguments. A Local Location Broker process ( llbd ) must be running on the local 
host when nrglbd is started. 

You can run only one nrglbd on a network or internet. 

The following command procedure starts the GLB process nrglbd on a VMS 
system: 

SYS$STARTUP:RPC$UCX_STARTUP.COM 

The process has no qualifiers and takes no arguments. It should run as a detached 
process, independently of login activity for as long as the system is up. 

The following example shows the line in the command procedure that starts the 
process. 

$ RUN/DETACHED/PRIV=SYSPRV/PROCESS NAME=RPC$NRGLBD RPC$EXE:RPC$NRGLBD.EXE 
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Qualifier 


-version Display the version of the Network Computing Kernel (NCK) that this 
nrglbd belongs to but do not start the process. (NCK is part of the 
Network Computing System (NCS) on which DECrpc is based.) 

Restrictions 

This section discusses the procedure to follow if the system running the nrglbd is 
taken off-line. 

If you restart nrglbd on the same system and no server on any other system 
changed state, all things should run as before. If, however, an application tries to 
contact a server that is no longer running or which has different port numbers, the 
application will fail. The application also will not see any new server registrations. 

If a copy of glbdbase. dat is not available, you must create an up to date version 
of the file before restarting nrglbd. To do so, use lb_$admin to query the 
1 lbd for registration data on every system running a DECrpc server and to register 
all DECrpc servers with the GLB on the new host. Then restart nrglbd. 


See Also 

lb_$admin, llbd 
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Glossary 


address family 

A set of communications protocols that use a common addressing 
mechanism to identify endpoints. The terms address family and 
protocol family are used synonymously in this manual. 

Berkeley UNIX socket abstraction 

A network programming abstraction, developed by the University of 
California at Berkeley, that is independent of communications protocols 
and is based on the concept of sending and receiving datagrams. 

broadcast 

To send a remote procedure call request to all hosts in a network, 
broker 

A server that manages information resources. A Location Broker is a 
broker. 

client 

A process that uses resources. In the context of this manual, a client is 
a program that makes remote procedure calls. A client imports one or 
more interfaces. See also server. 

export an interface 

To provide the operations defined by an interface. A server exports an 
interface to a client. See also import an interface. 

forward 

To dispatch a remote procedure call request to a server that exports the 
requested interface for the requested object. The Local Location Broker 
(LLB) forwards remote procedure calls that are sent to the LLB 
forwarding port on a server host. 

Global Location Broker (GLB) 

A server that maintains global information about objects on a network 
or an internet. Part of the DECrpc Location Broker. The server runs as 
the nrglbd process. 

implement an interface 

Provide access to one or more objects. A server, a program that 
provides such access, accepts requests for operations in any of its 
interfaces. When it receives a request from a client, it executes the 




procedures that perform the operation and it sends a response to the 
client. 

import an interface 

To request the operations defined by an interface. A client imports an 
interface from a server. See also export. 

interface 

A set of operations. The Network Interface Definition Language 
defines interfaces. 

interface UUID 

A Universal Unique Identifier (UUID) that permanently identifies a 
particular interface. Both the Remote Procedure Call (RPC) run-time 
library and the Location Broker use interface UUIDs to specify 
interfaces. 

internet 

A set of two or more connected networks. The networks in an internet 
do not necessarily use the same communications protocol. 

Local Location Broker (LLB) 

A server that maintains information about objects on the local host. The 
LLB also provides the Location Broker forwarding facility. 

Location Broker 

A set of software including the Local Location Broker, the Global 
Location Broker, and the Location Broker Client Agent. The Location 
Broker maintains information about the locations of objects and 
interfaces. 

Location Broker Client Agent 

Part of the Location Broker. Programs communicate with Global 
Location Brokers and Local Location Brokers by means of the Location 
Broker Client Agent. 

manager 

A set of procedures that implement the operations in one interface for 
objects of one type. It is possible for a server to export several 
interfaces or to export an interface for several types of objects; each 
combination of interface and type has its own manager. 

network 

Data transmission media through which computers can be connected. 

Network Computing System (NCS) 

A set of software components that conform to the Network Computing 
Architecture. These components include the Remote Procedure Call 
run-time library, the Location Broker, and the Network Interface 
Definition Language (NIDL) Compiler. The DECrpc is based on NCS. 
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network ID 

Part of the network address that uniquely identifies a network. In the 
Internet, the number of bits that indicate the network ID are determined 
by the address class. In class A addresses, 7 bits indicate the network 
ID; in class B addresses, 14 bits indicate the network ID; in class C 
addresses, 22 bits indicate the network ID. 

NIDL Compiler 

A tool that converts an interface definition written in Network Interface 
Definition Language (NIDL) into several program modules, including 
source code for client and server stubs. The NIDL Compiler accepts 
interface definitions written in the C syntax of NIDL; it generates C 
source code and header files. 

Network Interface Definition Language(NIDL) 

A declarative language for the definition of interfaces. The NIDL 
syntax resembles the syntax of the C programming language. 

object 

An entity that is manipulated by well-defined operations. Disk files, 
printers, and array processors are examples of objects. Objects are 
accessed though interfaces. Every object has a type. 

object UUID 

A Universial Unique Identifier (UUID) that identifies a particular 
object. Both the Remote Procedure Call (RPC) run-time library and the 
Location Broker use object UUIDs to identify objects. 

operation 

A procedure through which an object is accessed or manipulated. 

port 

A specific communications endpoint within a host. A port is identified 
by a port number. See also socket. 

port number 

One of the three parts in a socket address. For example, the character 
string 77 might represent a port number, while ip.wooster[77] might 
represent a socket address. 

protocol family 

A set of communications protocols, for example, the Department of 
Defense Internetwork Protocols. All members of a protocol family use 
a common addressing mechanism to identify endpoints. The terms 
protocol family and address family are synonymous. 

register an object and an interface with the Location Broker 

To enter in the Location Broker database an object and the location of a 
server that exports an interface for that object. Servers register with the 
Location Broker. Clients can use Location Broker lookup calls to 
determine the locations of registered objects. 
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register an object with the Remote Procedure Call (RPC) run-time library 
To enter an object and its location with the rpc_$register_mgr 
routine. An internal mechanism that allows an application to make 
remote procedure calls to remote hosts. 

remote procedure call 

An invocation of a remote operation. You can make remote procedure 
calls between processes on different hosts or on the same host. 

Remote Procedure Call (RPC) run-time library 

The set of rpc_$ library routines that DECrpc provides to implement 
a remote procedure call mechanism. 

server 

A process that implements interfaces. In the context of this manual, a 
server whose procedures can be invoked from remote hosts. A server 
exports one or more interfaces to one or more objects. 

socket 

An endpoint of communications in the form of a message queue. A 
socket is identified by a socket address. See also Berkeley UNIX 
socket abstraction. 

socket address 

A data structure that uniquely identifies a specific communications 
endpoint. A socket address consists of a port number and a network 
address. 

type 

A class of object. All objects of a specific type can be accessed though 
the same interface or interfaces. 

type UUID 

A Universal Unique Identifier (UUID) that identifies a particular type. 
Both the Remote Procedure Call (RPC) run-time library and the 
Location Broker use type UUIDs to specify types. 

Universal Unique Identifier (UUID) 

An identifier used by the Network Computing System to identify 
interfaces, objects, and types. 

well known port 

A port whose port number is part of the definition of an interface. 
Clients of the interface always send to that port; servers always listen 
on that port. Some well known ports are assigned to particular servers 
by the administrators of a protocol. For example, the administrators of 
the Internet Protocols have assigned the port number 23 to the telnet 
remote login facility. 
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